Skip to content

drivers: add experimental APC Microlink serial driver#3406

Open
libschmudie-so wants to merge 20 commits into
networkupstools:masterfrom
NetCube-Systems-Austria:master
Open

drivers: add experimental APC Microlink serial driver#3406
libschmudie-so wants to merge 20 commits into
networkupstools:masterfrom
NetCube-Systems-Austria:master

Conversation

@libschmudie-so
Copy link
Copy Markdown

Implement a new apcmicrolink driver for APC Smart-UPS units that expose the Microlink serial protocol over the RJ45 serial interface.

The driver establishes a Microlink session over the serial link, reads and parses the device descriptor blob at runtime, and uses that descriptor map to publish standard NUT variables, writable settings, alarms, and supported instant commands. It also adds labeled Microlink command masks for battery tests, runtime calibration, UPS control, and outlet-group power control, including APC-style load., shutdown., and outlet.group.N.* commands.

The driver now uses the Microlink UPS status word for ups.status, exposes input.transfer.reason from the UPS status change cause enum, and avoids folding simple-signaling bits into the synthesized NUT status. The patch also adds the driver to the build and hardware lists, documents configuration and current limitations, and cleans up initial upstream review issues such as missing file headers, whitespace, and format-string warnings.

Tested against:

APC Smart-UPS 750 (SMT750RMI2UC)

Coding helper disclosure: Codex

General points

  • Described the changes in the PR submission or a separate issue, e.g.
    known published or discovered protocols, applicable hardware (expected
    compatible and actually tested/developed against), limitations, etc.

  • There may be multiple commits in the PR, aligned and commented with
    a functional change. Notably, coding style changes better belong in a
    separate PR, but certainly in a dedicated commit to simplify reviews
    of "real" changes in the other commits. Similarly for typo fixes in
    comments or text documents.

  • Use of coding helper tools and AI should be disclosed in the commit
    or PR comments (it is interesting to know which ones do a decent job).
    As with other contributions, a human is responsible and thanked for the
    quality and content of the change, and is presumed to have the right to
    post that code to be published further under the project's license terms.

  • Please star NUT on GitHub, this helps with sponsorships! ;)

Frequent "underwater rocks" for driver addition/update PRs

  • Revised existing driver families and added a sub-driver if applicable
    (nutdrv_qx, usbhid-ups...) or added a brand new driver in the other
    case.

  • Did not extend obsoleted drivers with new hardware support features
    (notably blazer and other single-device family drivers for Qx protocols,
    except the new nutdrv_qx which should cover them all).

  • For updated existing device drivers, bumped the DRIVER_VERSION macro
    or its equivalent.

  • For USB devices (HID or not), revised that the driver uses unique
    VID/PID combinations, or raised discussions when this is not the case
    (several vendors do use same interface chips for unrelated protocols).

  • For new USB devices, built and committed the changes for the
    scripts/upower/95-upower-hid.hwdb file

  • Proposed NUT data mapping is aligned with existing docs/nut-names.txt
    file. If the device exposes useful data points not listed in the file, the
    experimental.* namespace can be used as documented there, and discussion
    should be raised on the NUT Developers mailing list to standardize the new
    concept.

  • Updated data/driver.list.in if applicable (new tested device info)

Frequent "underwater rocks" for general C code PRs

  • Did not "blindly assume" default integer type sizes and value ranges,
    structure layout and alignment in memory, endianness (layout of bytes and
    bits in memory for multi-byte numeric types), or use of generic int where
    language or libraries dictate the use of size_t (or ssize_t sometimes).

  • Progress and errors are handled with upsdebugx(), upslogx(),
    fatalx() and related methods, not with direct printf() or exit().
    Similarly, NUT helpers are used for error-checked memory allocation and
    string operations (except where customized error handling is needed,
    such as unlocking device ports, etc.)

  • Coding style (including whitespace for indentations) follows precedent
    in the code of the file, and examples/guide in docs/developers.txt file.

  • For newly added files, the Makefile.am recipes were updated and the
    make distcheck target passes.

General documentation updates

  • Added a bullet point into NEWS.adoc, possibly also UPGRADING.adoc
    if there is something packagers or custom-build users should take into
    account (new driver categories, configuration options, dependencies...)

  • Updated docs/acknowledgements.txt (for vendor-backed device support)

  • Added or updated manual page information in docs/man/*.txt files
    and corresponding recipe lists in docs/man/Makefile.am for new pages

  • Passed make spellcheck, updated spell-checking dictionary in the
    docs/nut.dict file if needed (did not remove any words -- the make
    rule printout in case of changes suggests how to maintain it).

Additional work may be needed after posting this PR

  • Propose a PR for NUT DDL with detailed device data dumps from tests
    against real hardware (the more models, the better).

  • Address NUT CI farm build failures for the PR: testing on numerous
    platforms and toolkits can expose issues not seen on just one system.

  • Revise suggestions from LGTM.COM analysis about "new issues" with
    the changed codebase.

@github-actions
Copy link
Copy Markdown

github-actions Bot commented Apr 12, 2026

A ZIP file with standard source tarball and another tarball with pre-built docs for commit 1fdc538 is temporarily available: NUT-tarballs-PR-3406.zip.

@AppVeyorBot
Copy link
Copy Markdown

@AppVeyorBot
Copy link
Copy Markdown

@jimklimov
Copy link
Copy Markdown
Member

This looks very solid, thanks!

CI disliked something about dist recipes though; while at it - the man page HTML rendering is not listed in the Makefile.am. I'm on a phone commuting now, so can't look deeper.

@AppVeyorBot
Copy link
Copy Markdown

@AppVeyorBot
Copy link
Copy Markdown

jimklimov added a commit to jimklimov/nut that referenced this pull request Apr 13, 2026
jimklimov added a commit to jimklimov/nut that referenced this pull request Apr 13, 2026
…#3406]

Signed-off-by: Jim Klimov <jimklimov+nut@gmail.com>
@jimklimov jimklimov added this to the 2.8.6 milestone Apr 13, 2026
@jimklimov jimklimov added serial port AI For good or bad, machine tools are upon us. Humans are still the responsible ones. labels Apr 13, 2026
Comment thread drivers/apcmicrolink.c Dismissed
Comment thread drivers/apcmicrolink.c Fixed
Comment thread drivers/apcmicrolink.c Fixed
Comment thread drivers/apcmicrolink.c Fixed
Comment thread drivers/apcmicrolink.c Fixed
Comment thread drivers/apcmicrolink.c Fixed
@jimklimov
Copy link
Copy Markdown
Member

@libschmudie-so : Cheers, your PR is made from your master branch and not with a toggle that I can edit it as a maintainer, so I posted a couple of recipe fixes as PRs into your fork. Hopefully they should get the CI builds passing.

Is this a personal or corporate-backed contribution? Feel free to add a note in acknowledgements.txt in the latter case.

jimklimov added a commit to jimklimov/nut that referenced this pull request Apr 13, 2026
Signed-off-by: Jim Klimov <jimklimov+nut@gmail.com>
libschmudie-so added a commit to NetCube-Systems-Austria/nut that referenced this pull request Apr 13, 2026
docs/man/Makefile.am: provide apsmicrolink.html also [networkupstools#3406]
libschmudie-so added a commit to NetCube-Systems-Austria/nut that referenced this pull request Apr 13, 2026
drivers/Makefile.am: EXTRA_DIST apcmicrolink-maps.h apcmicrolink.h [networkupstools#3406]
libschmudie-so added a commit to NetCube-Systems-Austria/nut that referenced this pull request Apr 13, 2026
NEWS.adoc: introduce apcmicrolink driver [networkupstools#3406]
@AppVeyorBot
Copy link
Copy Markdown

@AppVeyorBot
Copy link
Copy Markdown

@jimklimov
Copy link
Copy Markdown
Member

Yeah, now it is sad about spelling checks. Do you have aspell? Run make spellcheck-interactive-quick and it should arrange an interface to add the new words. Alternately, edit docs/nut.dict to same effect (bumping the number of entries in the top line, in the end):

FAILED : Aspell reported errors here:
----- vvv
600:& apcmicrolink 2 32: apc microlink, apc-microlink
688:& RMI 18 29: RIM, REMI, MRI, EMI, RM, MI, RI, ROM, RUM, RAMIE, RAM, REM, RMS, RBI, RSI, RIME, RAMA, ROME
----- ^^^
make[5]: *** [/home/runner/work/nut/nut/nut-2.8.5.13.7/_build/sub/docs/Makefile:1875: ../NEWS.adoc-spellchecked] Error 1
=====================================================================
FAILED automatic spellcheck for the following sources (relative to /home/runner/work/nut/nut/nut-2.8.5.13.7/_build/sub/docs) using custom dictionary file 'nut.dict':  ../../../docs/../NEWS.adoc
=====================================================================
Please 'cd /home/runner/work/nut/nut/nut-2.8.5.13.7/_build/sub && make spellcheck-interactive'
to either fix document sources or update the dictionary of accepted
words and spellings listed in the 'nut.dict' file there.
Either way, please follow up by posting a pull request or a patch
to integrate your fixes into the common NUT codebase.
=====================================================================
make[4]: *** [Makefile:1955: spellcheck] Error 1
  SUBDIR-MAKE	FAILURE: 'make spellcheck' in docs
make[3]: *** [Makefile:2119: spellcheck/docs] Error 2
  ASPELL	Spell checking on /home/runner/work/nut/nut/nut-2.8.5.13.7/docs/man/apcmicrolink.txt
FAILED : Aspell reported errors here:
----- vvv
70:& APCMICROLINK 2 1: APC MICROLINK, APC-MICROLINK
127:& apcmicrolink 2 1: apc microlink, apc-microlink
205:& apcmicrolink 2 2: apc microlink, apc-microlink
258:& apcmicrolink 2 2: apc microlink, apc-microlink
340:& apcmicrolink 2 2: apc microlink, apc-microlink
420:& apcmicrolink 2 6: apc microlink, apc-microlink
767:& apcmicrolink 2 14: apc microlink, apc-microlink
857:& showinternals 32 2: show internals, show-internals, internals, internalise, swindlers, centennials, internalize, sentinels, swindler's, bicentennials, fontanels, centennial's, vintners, swindles, Shantung's, shantung's, sentinel's, vintner's, swindle's, windfalls, wantons, tercentennials, bicentennial's, fontanel's, wanton's, wantonly, windlass, Chinatown's, winding's, windfall's, tercentennial's, Wendell's
1324:& showunmapped 9 2: show unmapped, show-unmapped, unmapped, swamped, shrimped, chomped, shampooed, wimped, champed
1628:& testinterval 6 12: test interval, test-interval, distinctively, distantly, distasteful, distastefully
1842:& Lukas 55 3: Lucas, Lucks, Lurks, Leaks, Luke's, Likes, Luck's, Lugs, Lakes, Lug's, Luges, Licks, Lula's, Lags, Lucas's, Lick's, Like's, Luaus, Lurkers, Ukase, Las, Luisa, Lacks, Larks, Leeks, Locks, Looks, Leak's, Skuas, Luna's, Lax, Lux, Loki's, Lu's, Luca, Luis, Luke, Lack's, Lake's, Lark's, Leas, Leek's, Lock's, Look's, UK's, LG's, Flukes, Lac's, Lag's, La's, Lusaka's, Lanka's, Luau's, Lea's, Fluke's
2251:& Schmid 12 9: Schmidt, Sch mid, Sch-mid, Chmod, Schmo, Schmier, Schemed, Schmo's, Schist, Chimed, Shamed, Schizoid
----- ^^^
make[6]: *** [/home/runner/work/nut/nut/nut-2.8.5.13.7/_build/sub/docs/Makefile:1875: apcmicrolink.txt-spellchecked] Error 1

@jimklimov
Copy link
Copy Markdown
Member

jimklimov commented Apr 13, 2026

There are also compiler complaints from static analysis, like:

apcmicrolink.c:335:49: error: format string is not a string literal [-Werror,-Wformat-nonliteral]
  335 |         written = vsnprintf(buf + *pos, buflen - *pos, fmt, ap);
      |                                                        ^~~
apcmicrolink.c:453:25: error: format string is not a string literal [-Werror,-Wformat-nonliteral]
  453 |                 snprintf(out, outlen, templ, rendered_index);
      |                                       ^~~~~
apcmicrolink.c:1028:10: error: enumeration value 'MLINK_DESC_NONE' not explicitly handled in switch [-Werror,-Wswitch-enum]
 1028 |         switch (entry->type) {
      |                 ^~~~~~~~~~~
apcmicrolink.c:1280:12: error: enumeration value 'MLINK_DESC_NONE' not explicitly handled in switch [-Werror,-Wswitch-enum]
 1280 |                         switch (entry->type) {
      |                                 ^~~~~~~~~~~
apcmicrolink.c:1999:11: error: enumeration value 'MLINK_DESC_WRITE_NONE' not explicitly handled in switch [-Werror,-Wswitch-enum]
 1999 |                 switch (entry->write_type) {
      |                         ^~~~~~~~~~~~~~~~~
5 errors generated.

For the switch, they have two conflicting requirements ("must have a default", and "do not need a default when all possible enum values were listed"), so we use a copy-paste block of pragmas to quiesce that. So list all enum values where needed, and add a default: surrounded by those pragmas, many examples in code for that. Probably the case for value(s) you did not list yet go just above that default line :)

For the formatting string, see {v,}snprintf_dynamic() etc. which validate that the actual fmt_dynamic formatting string you used matches the percent-argument template (which to compiler corresponds to the varargs passed to this fmt_reference parameter as if it were the formatting string). OTOH, something like snprintf_dynamic(out, outlen, templ, "%i", rendered_index); would be the fix.

@AppVeyorBot
Copy link
Copy Markdown

@AppVeyorBot
Copy link
Copy Markdown

Signed-off-by: Lukas Schmid <lukas.schmid@netcube.li>
@AppVeyorBot
Copy link
Copy Markdown

Signed-off-by: Lukas Schmid <lukas.schmid@netcube.li>
@AppVeyorBot
Copy link
Copy Markdown

Build nut 2.8.5.4713-master completed (commit 140fc68627 by @libschmudie-so)

@AppVeyorBot
Copy link
Copy Markdown

@libschmudie-so
Copy link
Copy Markdown
Author

@jimklimov Stupid question, but can you tell me what I am missing regarding the issue in "GHA-01: Tarballs / Make Dist and Docs Tarballs, see workflow page for links". It works locally and with ci_build.sh at this point without errors...

@AppVeyorBot
Copy link
Copy Markdown

@AppVeyorBot
Copy link
Copy Markdown

@AppVeyorBot
Copy link
Copy Markdown

Signed-off-by: Lukas Schmid <lukas.schmid@netcube.li>
@AppVeyorBot
Copy link
Copy Markdown

Build nut 2.8.5.4718-master completed (commit f9204fadbd by @libschmudie-so)

@AppVeyorBot
Copy link
Copy Markdown

Signed-off-by: Lukas Schmid <lukas.schmid@netcube.li>
@libschmudie-so
Copy link
Copy Markdown
Author

@jimklimov Stupid question, but can you tell me what I am missing regarding the issue in "GHA-01: Tarballs / Make Dist and Docs Tarballs, see workflow page for links". It works locally and with ci_build.sh at this point without errors...

Nevermind I think i figured it out...

@AppVeyorBot
Copy link
Copy Markdown

Build nut 2.8.5.4723-master completed (commit 6c64df88b0 by @libschmudie-so)

Signed-off-by: Lukas Schmid <lukas.schmid@netcube.li>
@libschmudie-so
Copy link
Copy Markdown
Author

@jimklimov I think I have every fixed up and am also using some stuff shared with apc_modbus now as it is indeed similar. Is there anything left from your side?

@AppVeyorBot
Copy link
Copy Markdown

Build nut 2.8.5.4727-master completed (commit 5a3d7ef674 by @libschmudie-so)

Comment thread drivers/apcmicrolink.c Dismissed
…d clang [networkupstools#3406]

Signed-off-by: Jim Klimov <jimklimov+nut@gmail.com>
Copy link
Copy Markdown
Member

@jimklimov jimklimov left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is quite a significant body of work, now with refactoring/simplification that seems generally beneficial, but I would welcome a review from @EchterAgo as this change impacts the driver maintained by him, just to make sure I did not miss something critical.

As for the review, it seems there is one line that should be dropped to pass CI across the board (PR against source branch posted), and highlighted several spots where I think it would be more maintainable to write the code differently, but I am open to being convinced I misunderstood a greater scheme :) Otherwise LGTM upon at least a cursory reading.

Comment thread drivers/apcmicrolink.c Outdated
Comment thread drivers/apc_common.c
#include "apc_common.h"

const apc_value_map_t apc_input_quality_map[] = {
{ (1U << 0), "Acceptable" },
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here and below, is there a particular reason to NOT use textual names defined in the header for same bit-shifted values (avoid possible discrepancies if only one of the explicit bit-shifts somehow gets edited later without concern for the other)?

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As far as I know not all have a matching enum, but for those that do I can of course use the enum values. They pretty much just came straight out of apcmicrolink-maps without much changing, thats why it doesn't have the enums in there.

Comment thread drivers/apc_common.c
return 0;
}

time_stamp = ((time_t)value * 86400) + ((time_t)10957 * 86400);
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Rather a question of style and maintainability than a requirement to change: why was 10957 hard-coded here and not defined as a macro or static number? e.g. as dropped from apc_modbus.c:

static const time_t apc_date_start_offset = 946684800; /* 2000-01-01 00:00 */

Wondering if the specific numbers would differ as/when/if this code migrates to 64-bit time sooner or later.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I honestly haven't thought about it that much. The value from the UPS was in days so the 10957 in days made sense to me. I guess we could pull it out into a static or macro tho.

#include "apcmicrolink-maps.h"

static const microlink_value_map_t microlink_outlet_status_map[] = {
{ (1U << 0), "StateOn" },
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same question as elsewhere about use of bit-shift values explicitly vs. enum value textual names, to avoid future surprises.

Comment thread drivers/apc_common.c
@@ -0,0 +1,357 @@
/* apc_common.c - Shared APC driver helpers
*
* Copyright (C) 2026 Lukas Schmid <lukas.schmid@netcube.li>
Copy link
Copy Markdown
Member

@jimklimov jimklimov May 18, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just in case: is there some code (transplanted map contents) that would warrant adding Copyright © 2023 Axel Gembe <axel@gembe.net> here?

CC @EchterAgo

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

From what I recall the functions in here are what I had written, but they probably are inspired from the apc_modbus so I'll just add the copyright in there too.

Comment thread drivers/apcmicrolink.c
return 0;
}

static int microlink_parse_bool(const char *text, int *value)
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note to self: this could be useful in #2811 :)

libschmudie-so and others added 2 commits May 18, 2026 22:06
drivers/apcmicrolink.c: drop pragma to ignore a warning unknown to old clang
…st inspired by the original code from apc-modbus

Signed-off-by: Lukas Schmid <lukas.schmid@netcube.li>
@AppVeyorBot
Copy link
Copy Markdown

Build nut 2.8.5.4741-master completed (commit a0e8bd7409 by @libschmudie-so)

@AppVeyorBot
Copy link
Copy Markdown

Build nut 2.8.5.4742-master completed (commit b1ae14653a by @libschmudie-so)

@AppVeyorBot
Copy link
Copy Markdown

Build nut 2.8.5.4743-master completed (commit fb8908dfda by @libschmudie-so)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

AI For good or bad, machine tools are upon us. Humans are still the responsible ones. APC feature serial port

Projects

Status: Todo

Development

Successfully merging this pull request may close these issues.

6 participants